Inside Macintosh: Memory
Previous | Chapter Top | Chapter Contents | Next |
You can use the NewHandle function to allocate a relocatable block of memory. If you want to allocate new blocks of memory with their bits precleared to 0, you can use the NewHandleClear function.
You should not call any of these memory-allocation routines at interrupt time.
You can use the DisposeHandle procedure to free relocatable blocks of memory you have allocated.
You can use the NewHandle function to allocate a relocatable memory block of a specified size.
FUNCTION NewHandle (logicalSize: Size): Handle;
The NewHandle function attempts to allocate a new relocatable block in the current heap zone with a logical size of logicalSize bytes and then return a handle to the block. The new block is unlocked and unpurgeable. If NewHandle cannot allocate a block of the requested size, it returns NIL .
Do not try to manufacture your own handles without this function by simply assigning the address of a variable of type Ptr to a variable of type Handle . The resulting "fake handle" would not reference a relocatable block and could cause a system crash.
The NewHandle function pursues all available avenues to create a block of the requested size, including compacting the heap zone, increasing its size, and purging blocks from it. If all of these techniques fail and the heap zone has a grow-zone function installed, NewHandle calls the function. Then NewHandle tries again to free the necessary amount of memory, once more compacting and purging the heap zone if necessary. If memory still cannot be allocated, NewHandle calls the grow-zone function again, unless that function had returned 0, in which case NewHandle gives up and returns NIL .
Because NewHandle allocates memory, you should not call it at interrupt time.
The registers on entry and exit for NewHandle are
Registers on exit |
|
|---|---|
If you want to clear the bytes of a block of memory to 0 when you allocate it with the NewHandle function, set bit 9 of the routine trap word. You can usually do this by supplying the word CLEAR as the second argument to the routine macro, as follows:
_NewHandle ,CLEAR
If you allocate a relocatable block that you plan to lock for long periods of time, you can prevent heap fragmentation by allocating the block as low as possible in the heap zone. To do this, see the description of the ReserveMem procedure on ReserveMem .
If you plan to lock a relocatable block for short periods of time, you might want to move it to the top of the heap zone to prevent heap fragmentation. For more information, see the description of the MoveHHi procedure on MoveHHi .
You can use the NewHandleClear function to allocate prezeroed memory in a relocatable block of a specified size.
FUNCTION NewHandleClear (logicalSize: Size): Handle;
The NewHandleClear function works much as the NewHandle function does but sets all bytes in the new block to 0 instead of leaving the contents of the block undefined.
Currently, NewHandleClear clears the block one byte at a time. For a large block, it might be faster to clear the block manually a long word at a time.
When you are completely done with a relocatable block, call the DisposeHandle procedure to free it and its master pointer for other uses.
PROCEDURE DisposeHandle (h: Handle);
The DisposeHandle procedure releases the memory occupied by the relocatable block whose handle is h . It also frees the handle's master pointer for other uses.
After a call to DisposeHandle , all handles to the released block become invalid and should not be used again. Any subsequent calls to DisposeHandle using an invalid handle might damage the master pointer list.
Do not use DisposeHandle to dispose of a handle obtained from the Resource Manager (for example, by a previous call to GetResource ); use ReleaseResource instead. If, however, you have called DetachResource on a resource handle, you should dispose of the storage by calling DisposeHandle .
Because DisposeHandle purges memory, you should not call it at interrupt time.